home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / IOIterator.a < prev    next >
Encoding:
Text File  |  1996-05-01  |  3.9 KB  |  116 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        IOIterator.a
  3. ;
  4. ;    Contains:    xxx put contents here xxx
  5. ;
  6. ;    Version:    Technology:    xxx put the technology version here xxx
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__IOITERATOR__') = 'UNDEFINED' THEN
  19. __IOITERATOR__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF FOR_SYSTEM8_PREEMPTIVE THEN
  25. ;  typedefs
  26. ; typedef UInt32                         IteratorDescVersion
  27.  
  28. ;
  29. ;###########################################################
  30. ; How to use the IteratorDescVersion
  31. ;###########################################################
  32. ; Each family will define a k<Family>CurrentIteratorDescVersion constant
  33. ; in its *.i file. The client will check the returned IteratorDescVersion
  34. ;    value against this constant to make sure there's no version mismatch 
  35. ;     problem.
  36. ; Common data structure used by all I/O family iterators
  37. ;
  38. IODeviceRef                RECORD 0
  39. contents                 ds.l    4                ; offset: $0 (0)
  40. sizeof                     EQU *                    ; size:   $10 (16)
  41.                         ENDR
  42. ;
  43. ; a family unique reference number for returned devices.
  44. ; this is an opaque field, for now, use the name registry Ref value of the             
  45. ;    device in question.    
  46. ; The IODeviceRef is unique within a family, NOT unique across the entire I/O name space
  47. ;
  48. IOCommonInfo            RECORD 0
  49. ref                         ds        IODeviceRef        ; offset: $0 (0)
  50. versionNumber             ds.l    1                ; offset: $10 (16)
  51. sizeof                     EQU *                    ; size:   $14 (20)
  52.                         ENDR
  53. ;  IteratorDescVersion versionNumber: version number of the family specific IOIteratorData
  54.     ENDIF
  55. ;
  56. ;###########################################################
  57. ; How to copy name registry ref --> IODeviceRef
  58. ;###########################################################
  59. ;{
  60. ;    IOCommonInfo            DeviceData;
  61. ;    RegEntryRef                *anotherReg, *whichDevice;
  62. ;    anotherReg = (RegEntryRef *)&DeviceData;
  63. ;    *anotherReg = *whichDevice;
  64. ;}
  65. ;###########################################################
  66. ; How to define a family specific IOIteratorData structure
  67. ;###########################################################
  68. ; struct <FamilyName>IOIteratorData
  69. ; {
  70. ;      IOCommonInfo     IOCI;    
  71. ;                    // common data for all families    
  72. ;        f1,            // Individual family specific data
  73. ;        f2,
  74. ;        etc...
  75. ; };
  76. ; Example 1: (A possible implementation for the SCSI iterator)
  77. ;    struct SCSIIOIteratorData
  78. ; {
  79. ;      IOCommonInfo     IOCI;    
  80. ;                    // common data for all families    
  81. ;        UInt32            BusID;
  82. ;        UInt32            TargetID;
  83. ;        UInt32            LUN;
  84. ; };
  85. ;###########################################################
  86. ; How to define a family specific iterator function
  87. ;###########################################################
  88. ;OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  89. ;            (    ItemCount             requestItemCount,
  90. ;                FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),                              
  91. ;                ItemCount             *totalItemCountPtr );
  92. ;                
  93. ; For returning ALL devices that the family have access to
  94. ; OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  95. ;            (    UInt32                familySpecificParam,
  96. ;                ItemCount             requestItemCount,
  97. ;                FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),
  98. ;                ItemCount             *totalItemCountPtr );
  99. ;                
  100. ; For returning a subset of devices, filtered by some family specific parameters
  101. ; EXAMPLES:
  102. ; OSStatus SCSIGetDeviceData 
  103. ;            (    ItemCount             requestItemCount,
  104. ;                ItemCount             *totalItemCountPtr,
  105. ;                SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  106. ; To get all scsi devices
  107. ; OSStatus SCSIBusGetDeviceData 
  108. ;            (    UInt32                BusID,
  109. ;                ItemCount             requestItemCount,
  110. ;                ItemCount             *totalItemCountPtr,
  111. ;                SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  112. ; To get all scsi devices that matches the input BusID
  113. ;
  114.     ENDIF ; __IOITERATOR__ 
  115.  
  116.